openapi: 3.1.0
info:
  title: Wia REST API User reference
  description: >-
    </br>A REST API to interact with Wia platform for user management for
    external IAM teams. </br> </br> To get started, please ensure you have the
    correct permissions and appropriate client credentials. If you have not been
    provided client credentials, please contact your representative.  </br>
    </br> The API is organised around REST. Our API has predictable
    resource-oriented URLs, accepts form-encoded request bodies, returns
    JSON-encoded responses, and uses standard HTTP response codes,
    authentication, and verbs.
  version: v1
components:
  securitySchemes:
    Organisation:
      type: http
      description: An application accessToken can be used
      scheme: bearer
      bearerFormat: Bearer
  parameters:
    id:
      name: id
      description: Id of Object
      in: path
      required: true
      schema:
        type: string
    organisationId:
      name: organisation.id
      description: Id of organisation
      in: query
      required: false
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Max number of rows to return
      required: false
      schema:
        type: integer
        format: int32
        example: 20
    page:
      name: page
      in: query
      description: Section of rows to return e.g. 0, 1 or 2
      required: false
      schema:
        type: integer
        format: int32
    sort:
      name: sort
      in: query
      description: 'Sort by Ascending or Descending order Default: DESC'
      required: false
      schema:
        type: string
        enum:
          - ASC
          - DESC
    order:
      name: order
      in: query
      description: Order by column e.g. id
      required: false
      schema:
        type: string
  schemas:
    AccessToken:
      type: object
      properties:
        token:
          type: string
          example: u_at_abc123def45678
        refreshToken:
          type: string
          example: u_rt_abc123def45678
        scope:
          type: string
          description: The Domain of the Access Token.
          example: user
        expiresIn:
          type: integer
          example: 36000
        createdAt:
          type: integer
          example: 1642759067045
    Organisation:
      type: object
      properties:
        id:
          type: string
          example: org_123abc456def
        name:
          type: string
          example: Test organisation
    OrganisationUser:
      type: object
      properties:
        id:
          type: string
          example: ou_abc123def
        firstName:
          type: string
          example: Pina
        lastName:
          type: string
          example: Colada
        fullName:
          type: string
          example: Pina Colada
        userId:
          type: string
          example: usr_abc123def
        emailAddress:
          type: string
          example: pina.colada@wia.io
        isAdmin:
          type: boolean
          example: false
        teams:
          type: array
          items:
            $ref: '#/components/schemas/Team'
    Space:
      type: object
      properties:
        id:
          type: string
          example: spc_abc123
        clientId:
          type: string
          example: client-specific-id
        name:
          type: string
          example: Test Space
        isPublic:
          type: boolean
          example: false
        disabled:
          type: boolean
          example: false
        avatar:
          type: object
          properties:
            default:
              type: string
              example: 1234-5342-5543-36AD
            url:
              type: string
              example: https://example.com/image
            thumbnail:
              type: string
              example: 1234-5342-5543-36AD
        owner:
          type: object
          properties:
            organisation:
              $ref: '#/components/schemas/Organisation'
    Team:
      type: object
      properties:
        id:
          type: string
          example: tem_123abc456def
        name:
          type: string
          example: Test organisation
        isAdmin:
          type: boolean
          example: false
        members:
          type: array
          items:
            $ref: '#/components/schemas/TeamMember'
    TeamMember:
      type: object
      properties:
        id:
          type: string
          example: usr_123abc456def
        fullName:
          type: string
          example: John Doe
        emailAddress:
          type: string
          example: hello@example.com
        organisationUserId:
          type: string
          example: ou_123abcdeg456
    User:
      type: object
      properties:
        id:
          type: string
          example: usr_abc123def
        firstName:
          type: string
          example: Pina
        lastName:
          type: string
          example: Colada
        fullName:
          type: string
          example: Pina Colada
        emailAddress:
          type: string
          example: pina.colada@wia.io
        isAdmin:
          type: boolean
          example: false
  responses:
    NotFound:
      description: The specified resource was not found.
    BadRequest:
      description: Bad Request.
    Unauthorised:
      description: Unauthorised.
    ServerError:
      description: Server Error.
servers:
  - url: https://api.wia.io/v1
    description: Production
paths:
  /auth/token:
    post:
      tags:
        - Auth
      description: Generate access token
      requestBody:
        content:
          application/json:
            schema:
              properties:
                clientId:
                  type: string
                  description: The client Id of the organisation
                clientSecret:
                  type: string
                  description: The client secret of the organisation
                refreshToken:
                  type: string
                  description: Required for refresh token
                grantType:
                  type: string
                  enum:
                    - client_credentials
                    - refresh_token
                  description: Define the type of grant
                scope:
                  type: string
                  enum:
                    - organisation
                  description: Define the access scope
              required:
                - client_id
                - client_secret
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /auth/token/revoke:
    post:
      tags:
        - Auth
      security:
        - Organisation: []
      description: Revoke Token
      requestBody:
        content:
          application/json:
            schema:
              properties:
                token:
                  description: The token to revoke
                  type: string
              required:
                - token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  revoked:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /organisations/users/:
    post:
      tags:
        - Organisation
      security:
        - Organisation: []
      description: Creates a user and adds them to an organisation
      requestBody:
        content:
          application/json:
            schema:
              properties:
                emailAddress:
                  description: Email Address of the user
                  type: string
                fullName:
                  description: Name of the user
                  type: string
                password:
                  description: Password for login
                  type: string
                loginViaSsoOnly:
                  description: >-
                    Boolean to indicate if the user can only login via SSO
                    (Password will be ignored)
                  type: string
              required:
                - emailAddress
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganisationUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /organisations/users:
    get:
      tags:
        - Organisation
      security:
        - Organisation: []
      description: List users of an organisation
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganisationUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /organisations/{organisationUserId}:
    get:
      tags:
        - Organisation
      security:
        - Organisation: []
      description: Retrieves organisation user with associated teams.
      parameters:
        - name: organisationUserId
          in: path
          required: true
          description: Id of the organisation user
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganisationUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /organisations/users/{organisationUserId}:
    put:
      tags:
        - Organisation
      security:
        - Organisation: []
      description: Updates details of an organisation user
      parameters:
        - name: organisationUserId
          in: path
          required: true
          description: Id of the organisation user to update
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                isAdmin:
                  description: Update whether an organisation User is an Admin
                  type: boolean
      responses:
        '200':
          description: Organisation user updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganisationUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Organisation
      security:
        - Organisation: []
      description: Remove a user from an organisation and delete the user
      responses:
        '200':
          description: User successfully removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /teams/{id}:
    get:
      tags:
        - Team
      security:
        - Organisation: []
      description: Retrieves the details of a specific team using its Id.
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the team to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: Team retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Team
      security:
        - Organisation: []
      description: Deletes a team by its Id.
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the team to be deleted.
          schema:
            type: string
      responses:
        '200':
          description: Team deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    description: Indicates whether the deletion was successful.
                    example: true
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /teams/:
    get:
      tags:
        - Team
      security:
        - Organisation: []
      description: Retrieves a list of all teams in an organisation.
      parameters:
        - name: limit
          in: query
          required: false
          description: Max number of results per page.
          schema:
            type: integer
        - name: page
          in: query
          required: false
          description: Page number for pagination.
          schema:
            type: integer
      responses:
        '200':
          description: List of teams retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Team
      security:
        - Organisation: []
      description: Creates a new team in an organisation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organisationId:
                  type: string
                  description: Public Id of the organisation.
                  example: org123
                name:
                  type: string
                  description: Name of the team to create.
                  example: Marketing Team
      responses:
        '200':
          description: Team created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '500':
          $ref: '#/components/responses/ServerError'
  /teams/{id}/members:
    post:
      tags:
        - Team
      security:
        - Organisation: []
      description: Adds a member to a specific team.
      parameters:
        - name: publicId
          in: path
          required: true
          description: Id of the team.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organisationUserId:
                  type: string
                  description: Id of the organisation User to add as a member.
                  example: ou_123abcder
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  added:
                    type: boolean
                    example: true
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Team
      security:
        - Organisation: []
      description: Removes member from a specific team.
      parameters:
        - name: publicId
          in: path
          required: true
          description: Id of the team.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organisationUserId:
                  type: string
                  description: Id of the user to remove as a member.
                  example: ou_123abcder
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    example: true
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /teams/{id}/members/{organisationUserId}:
    delete:
      tags:
        - Team
      security:
        - Organisation: []
      description: Removes a specific member from a team.
      parameters:
        - name: id
          in: path
          required: true
          description: Public Id of the team.
          schema:
            type: string
        - name: organisationUserId
          in: path
          required: true
          description: Id of the organisation user to remove.
          schema:
            type: string
      responses:
        '200':
          description: Member removed successfully.
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /spaces:
    get:
      tags:
        - Space
      security:
        - Organisation: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
        - name: country
          description: ISO 3166-1 alpha-3 country code
          in: query
          schema:
            type: string
            pattern: ^[A-Z]{3}$
          required: false
      description: Retrieve list of all Spaces
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Space'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /spaces/{id}/alerts/users/{organisationUserId}:
    post:
      tags:
        - Space
      security:
        - Organisation: []
      description: Add a user to space alerts
      parameters:
        - name: organisationUserId
          in: path
          required: true
          description: Id of the Organisation User to add to alerts
          schema:
            type: string
      responses:
        '200':
          description: User successfully added
          content:
            application/json:
              schema:
                type: object
                properties:
                  added:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Space
      security:
        - Organisation: []
      description: Remove a user from space alerts
      responses:
        '200':
          description: User successfully removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
tags:
  - name: Auth
    description: >-
      Endpoints related to authentication, including login, token management,
      and authorisation.
  - name: Organisation
    description: >-
      Endpoints that handle organisation-related operations, such as creation,
      management, and user assignments.
  - name: Team
    description: >-
      Endpoints focused on team management, including creating teams, managing
      members, and related operations.
  - name: Space
    description: >-
      Endpoints related to Spaces, including retrieval and management of
      space-specific settings and alerts.
